---
sidebar_label: Computed fields
sidebar_position: 11
description: Manage computed fields with the Hasura Metadata API
keywords:
  - hasura
  - docs
  - Metadata API
  - API reference
  - computed field
---

# Metadata API Reference: Computed Fields

## Introduction

**computed field** is an extra field added to a table, its value is
computed via an SQL function which has the table row type as an input
argument. Currently, the Hasura GraphQL Engine supports custom functions
returning [base types](https://www.postgresql.org/docs/current/extend-type-system.mdx#id-1.8.3.5.9)
or [table row types](https://www.postgresql.org/docs/current/rowtypes.mdx#ROWTYPES-DECLARING) as computed fields.

:::info Supported from

The Metadata API is supported for versions `v2.0.0` and above and
replaces the older [schema/Metadata API](/api-reference/schema-metadata-api/index.mdx).

:::

## pg_add_computed_field {#metadata-pg-add-computed-field}

`pg_add_computed_field` is used to define a computed field in a table.
There cannot be an existing column or relationship or computed field
with the same name.

Create a `computed field` called `full_name` on an `author` _table_,
using an SQL function called `author_full_name`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type":"pg_add_computed_field",
    "args":{
        "table":{
            "name":"author",
            "schema":"public"
        },
        "source": "default",
        "name":"full_name",
        "definition":{
            "function":{
                "name":"author_full_name",
                "schema":"public"
            },
            "table_argument":"author_row"
        }
    }
}
```

### Args syntax {#metadata-pg-add-computed-field-syntax}

| Key        | Required | Schema                                                                            | Description                                                                                                                                                                                                              |
| ---------- | -------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                             | Name of the table                                                                                                                                                                                                        |
| name       | true     | [ComputedFieldName](/api-reference/syntax-defs.mdx#computedfieldname)             | Name of the new computed field                                                                                                                                                                                           |
| definition | true     | [ComputedFieldDefinition](/api-reference/syntax-defs.mdx#computedfielddefinition) | The computed field definition                                                                                                                                                                                            |
| comment    | false    | `String`                                                                          | Customize the description shown in GraphQL introspection. If null or omitted then if a comment exists on the database function, it is used as the description, and if not, an autogenerated description is used instead. |
| source     | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                           | Name of the source database of the table (default: `default`)                                                                                                                                                            |

## pg_drop_computed_field {#metadata-pg-drop-computed-field}

`pg_drop_computed_field` is used to drop a computed field of a table. If
there are other objects dependent on this computed field, like
permissions, the request will fail and report the dependencies unless
`cascade` is set to `true`. If `cascade` is set to `true`, the dependent
objects are also dropped.

Drop a computed field `full_name` from a table `author`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type":"pg_drop_computed_field",
    "args":{
        "table":{
            "name":"author",
            "schema":"public"
        },
        "source": "default",
        "name":"full_name",
        "cascade": false
    }
}
```

### Args syntax {#metadata-pg-drop-computed-field-syntax}

| Key     | Required | Schema                                                                | Description                                                                                   |
| ------- | -------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| table   | true     | [TableName](/api-reference/syntax-defs.mdx#tablename)                 | Name of the table                                                                             |
| name    | true     | [ComputedFieldName](/api-reference/syntax-defs.mdx#computedfieldname) | Name of the computed field                                                                    |
| cascade | false    | Boolean                                                               | When set to `true`, all the dependent items (if any) on this computed fields are also dropped |
| source  | false    | [SourceName](/api-reference/syntax-defs.mdx#sourcename)               | Name of the source database of the table (default: `default`)                                 |

## bigquery_add_computed_field {#metadata-bigquery-add-computed-field}

`bigquery_add_computed_field` is used to define a computed field in a BigQuery table.
There cannot be an existing column or relationship or computed field
with the same name.

Create a `computed field` called `fetch_articles` on an `author` _table_,
using an SQL function called `author_fetch_articles`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type":"bigquery_add_computed_field",
    "args":{
        "table":{
            "name":"author",
            "dataset":"hasura"
        },
        "source": "bigquery",
        "name":"fetch_articles",
        "definition":{
            "function":{
                "name":"author_fetch_articles",
                "dataset":"hasura"
            },
            "argument_mapping": {
                "author_id_arg": "author_id"
            },
            "return_table": {
                "name": "article",
                "dataset": "hasura"
            }
        }
    }
}
```

### Args syntax {#metadata-bigquery-add-computed-field-syntax}

| Key        | Required | Schema                                                                                    | Description                                                                                                                                                                                                              |
| ---------- | -------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| table      | true     | [TableName](/api-reference/syntax-defs.mdx#bigquerytablename)                             | Name of the table                                                                                                                                                                                                        |
| source     | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)                                   | Name of the source database of the table                                                                                                                                                                                 |
| name       | true     | [ComputedFieldName](/api-reference/syntax-defs.mdx#computedfieldname)                     | Name of the computed field                                                                                                                                                                                               |
| definition | true     | [ComputedFieldDefinition](/api-reference/syntax-defs.mdx#bigquerycomputedfielddefinition) | The computed field definition                                                                                                                                                                                            |
| comment    | false    | `String`                                                                                  | Customize the description shown in GraphQL introspection. If null or omitted then if a comment exists on the database function, it is used as the description, and if not, an autogenerated description is used instead. |

## bigquery_drop_computed_field {#metadata-bigquery-drop-computed-field}

`bigquery_drop_computed_field` is used to drop a computed field of a table in a BigQuery source.
If there are other objects dependent on this computed field, like
permissions, the request will fail and report the dependencies unless
`cascade` is set to `true`. If `cascade` is set to `true`, the dependent
objects are also dropped.

Drop a computed field `fetch_articles` from a table `author`:

```http
POST /v1/metadata HTTP/1.1
Content-Type: application/json
X-Hasura-Role: admin

{
    "type":"bigquery_drop_computed_field",
    "args":{
        "table":{
            "name":"author",
            "dataset":"hasura"
        },
        "source": "bigquery",
        "name":"fetch_articles",
        "cascade": false
    }
}
```

### Args syntax {#metadata-bigquery-drop-computed-field-syntax}

| Key     | Required | Schema                                                                | Description                                                                                   |
| ------- | -------- | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| table   | true     | [TableName](/api-reference/syntax-defs.mdx#bigquerytablename)         | Name of the table                                                                             |
| source  | true     | [SourceName](/api-reference/syntax-defs.mdx#sourcename)               | Name of the source database of the table                                                      |
| name    | true     | [ComputedFieldName](/api-reference/syntax-defs.mdx#computedfieldname) | Name of the computed field                                                                    |
| cascade | false    | Boolean                                                               | When set to `true`, all the dependent items (if any) on this computed fields are also dropped |
